First Agent

In BindAI, an Agent is a core building block for AI applications. An agent can combine:

A language model provider
Instructions
Tools
Memory
Knowledge
Retrieval
Conversation context
Execution configuration
Middleware
Hooks and callbacks
Events

Agents provide a consistent execution interface while allowing additional capabilities to be added as your application grows.

Creating an Agent

The recommended way to configure an agent is through Agent.builder().

from bindai import Agent

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .build()
)

The builder provides a fluent interface for configuring the agent before it is created. Run the agent:

result = agent.run("Explain what BindAI is.")

print(result.output)

The run() method executes the agent and returns an AgentResult.

Agent Builder

Agent.builder() provides a fluent API for configuring an agent.

from bindai import Agent

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .build()
)

Common configuration areas include:

Configuration	Purpose
`.name()`	Set the agent name
`.model()`	Configure a provider-prefixed model
`.instructions()`	Configure agent instructions
`.tool()`	Add an individual tool
`.tools()`	Configure multiple tools
`.memory()`	Configure memory
`.knowledge()`	Configure knowledge
`.retriever()`	Configure retrieval
`.middleware()`	Configure middleware
`.build()`	Create the configured agent

The builder allows an application to compose an agent incrementally without manually constructing every supporting component.

Configuring a Model

A model can be configured using a provider-prefixed model identifier.

from bindai import Agent

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .build()
)

The provider prefix identifies the BindAI provider to use. Examples include:

.model("openai:gpt-4.1-mini")

.model("anthropic:claude-sonnet-4")

.model("ollama:llama3")

.model("groq:your-model")

.model("openrouter:your-model")

Google Gemini is also supported through the BindAI provider ecosystem. The exact model identifier depends on the provider and model being used.

Provider Configuration

BindAI separates agent configuration from the underlying model provider. Providers are registered through the BindAI provider system and can be selected using provider-prefixed model identifiers. This allows the same agent architecture to work with different model providers without changing the surrounding application structure. Current provider integrations include:

OpenAI
Anthropic
Google Gemini
Groq
Ollama
OpenRouter

Provider-specific configuration should be kept outside application source code whenever possible. Use environment variables or another secure configuration mechanism for API credentials.

Sending Prompts

The primary execution method is run().

result = agent.run("Explain dependency injection.")

The returned object is an AgentResult. The generated output can be accessed through:

print(result.output)

A basic agent therefore follows this pattern:

Create Agent
     │
     ▼
Configure Model
     │
     ▼
Configure Instructions
     │
     ▼
Build Agent
     │
     ▼
agent.run(...)
     │
     ▼
AgentResult

Chat and Conversation

BindAI agents can work with conversation state and conversational memory. A conversation-aware application can maintain previous interactions and use them as context for subsequent execution. The exact conversation behavior depends on the agent’s configured conversation and memory components. For applications that need persistent conversational state, configure an appropriate memory provider.

Structured Output

BindAI supports structured execution through its provider and execution abstractions. When using a provider that supports structured responses, an application can request output conforming to a defined Python type. For example, a Pydantic model can define the desired structure:

from pydantic import BaseModel


class Person(BaseModel):
    name: str
    age: int

Structured output configuration depends on the selected provider and execution path.

Provider support for specific structured-output features can vary. Always verify the capabilities of the model provider you are using.

Streaming

Agents also support streaming execution. Streaming is useful when an application needs incremental output instead of waiting for the complete execution result. For example:

stream = agent.stream(...)

Streaming integrates with BindAI’s execution context and execution pipeline. Use streaming for applications such as:

Interactive chat interfaces
Long-running responses
Incremental output processing
Real-time application interfaces

The exact streaming behavior depends on the configured provider and execution path.

Adding Tools

Tools allow an agent to perform actions through Python functions or other tool implementations. A simple tool can be created with BindAI’s tool decorator:

from bindai import tool


@tool
def add(a: int, b: int) -> int:
    return a + b

The tool can then be supplied to an agent:

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .tool(add)
    .instructions("You are a helpful assistant.")
    .build()
)

Multiple tools can also be configured:

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .tools(weather_tool, search_tool)
    .instructions("You are a helpful assistant.")
    .build()
)

The agent can make configured tools available to the model during execution.

Tool Registry

BindAI includes a tool registry and execution system for managing agent tools. This separates tool definition from agent execution and allows applications to organize reusable capabilities. A tool can represent:

A Python function
An external API
A database operation
A search operation
An application service
An external connection
An MCP-backed capability

Tool execution is integrated into the agent execution pipeline.

Adding Memory

Memory allows agents to retain information across interactions. Memory can be supplied through the agent configuration:

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .memory(memory)
    .instructions("You are a helpful assistant.")
    .build()
)

BindAI provides multiple memory implementations, including:

In-memory memory
SQLite
PostgreSQL
Vector memory
Pinecone
Chroma

Conversation memory can be combined with these capabilities to build conversational applications. See the Memory documentation for details.

Adding Knowledge

Knowledge allows an agent to use application-specific information during execution. A knowledge component can be supplied through the agent configuration:

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .knowledge(knowledge)
    .instructions("Answer questions using the available knowledge.")
    .build()
)

Knowledge can provide retrieved information as context for the agent. BindAI’s knowledge system supports:

Document ingestion
Parsing
Chunking
Embeddings
Metadata
Semantic retrieval
BM25 retrieval
Hybrid retrieval
Filtering
Reranking
Conversational retrieval
Knowledge pipelines

See the Knowledge documentation for the complete RAG architecture.

Adding a Retriever

Retrieval components can be configured for agents that need direct access to retrieved information. For example:

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .retriever(retriever)
    .instructions("Use retrieved information when answering questions.")
    .build()
)

BindAI supports multiple retrieval strategies, including:

Vector retrieval
BM25 retrieval
Hybrid retrieval

Retrieval configuration can be used independently or as part of a larger Knowledge/RAG architecture.

Middleware

Middleware provides a mechanism for applying cross-cutting behavior around agent execution. Middleware can be configured when building an agent:

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .middleware(middleware)
    .instructions("You are a helpful assistant.")
    .build()
)

Middleware can be useful for application-specific behavior such as:

Logging
Request processing
Output processing
Metrics
Validation
Other execution concerns

The exact behavior depends on the middleware implementation.

Events, Hooks, and Callbacks

BindAI provides event and lifecycle mechanisms around agent execution. Agents can work with an event bus and execution hooks to observe or customize execution behavior. Typical use cases include:

Logging execution
Monitoring agent activity
Recording execution results
Handling errors
Adding application-specific lifecycle behavior

These mechanisms allow application behavior to be extended without placing all logic directly inside the agent implementation.

Execution Configuration

Agent execution can be configured independently from the agent’s core model configuration. Execution configuration can control aspects of how the agent operates, including behavior around:

Tool execution
Context
Memory
Knowledge retrieval
Middleware
Execution lifecycle

This separation allows applications to evolve their execution behavior without replacing the agent abstraction itself.

Agent Context

Agents can operate with execution context containing information needed during an agent run. Context can connect the agent with application state and supporting execution components. This is particularly useful when an agent is part of a larger workflow or multi-agent application. For example:

Application
     │
     ▼
Agent
     │
     ├── Tools
     ├── Memory
     ├── Knowledge
     ├── Retrieval
     └── Execution Context

Context allows these components to participate in a coordinated execution pipeline.

Agent Delegation

BindAI agents can delegate work to other agents. Delegation is useful when a larger application is divided into specialized responsibilities. For example:

                    ┌── Research Agent
                    │
Main Agent ─────────┼── Writing Agent
                    │
                    └── Review Agent

A delegated agent can specialize in a particular task while the primary agent coordinates the larger operation. BindAI also supports team-oriented delegation and specialist role chains. This provides the foundation for multi-agent applications.

RAG-Enabled Agents

Agents can combine knowledge and retrieval with model execution. A typical RAG-enabled agent follows this flow:

User Question
      │
      ▼
Agent
      │
      ▼
Knowledge / Retriever
      │
      ▼
Relevant Documents
      │
      ▼
Context
      │
      ▼
Language Model
      │
      ▼
Agent Result

This allows agents to answer questions using application-specific information rather than relying only on the model’s built-in knowledge.

Agents in Workflows

Agents do not have to operate independently. They can be used as execution steps inside BindAI workflows. For example:

Workflow
   │
   ▼
Research Agent
   │
   ▼
Condition
   │
   ├───────────────┐
   ▼               ▼
Writing Agent    Review Agent
   │               │
   └───────┬───────┘
           ▼
         Result

This allows agent execution to participate in larger deterministic application flows. Workflows can additionally provide:

Conditions
Loops
Parallel execution
Retries
Timeouts
Scheduling
Human tasks

Direct Agent Construction

The Agent class is also publicly available:

from bindai import Agent

Direct construction is useful when an application already has the provider and supporting components configured. The constructor works with the underlying agent configuration and provider abstractions. For most application code, Agent.builder() is the more convenient approach because it provides a fluent configuration interface.

Complete Basic Example

A minimal BindAI agent can be configured as follows:

from bindai import Agent


agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful AI assistant.")
    .build()
)

result = agent.run("What is BindAI?")

print(result.output)

This is the basic foundation on which more advanced BindAI applications can be built.

Agent Development Flow

The typical development process is:

Choose a model provider.
Configure the agent.
Add instructions.
Add tools when actions are required.
Add memory when conversation state is required.
Add knowledge or retrieval when application-specific information is required.
Add middleware or hooks for cross-cutting execution behavior.
Integrate the agent into a workflow when multi-step orchestration is required.
Use delegation when responsibilities should be distributed across multiple agents.
Test the complete application.

The important principle is that capabilities can be added incrementally. Start with a simple agent and introduce additional components only when the application requires them.

Next Steps

After creating your first agent, continue with:

Getting Started

Core

Tools

Memory

Knowledge

Connections

Automation

Workflows

Projects

Templates

Roadmap

API Reference

01.4 first agent

First Agent

Creating an Agent

Agent Builder

Configuring a Model

Provider Configuration

Sending Prompts

Chat and Conversation

Structured Output

Streaming

Adding Tools

Tool Registry

Adding Memory

Adding Knowledge

Adding a Retriever

Middleware

Events, Hooks, and Callbacks

Execution Configuration

Agent Context

Agent Delegation

RAG-Enabled Agents

Agents in Workflows

Direct Agent Construction

Complete Basic Example

Agent Development Flow

Next Steps

​First Agent

​Creating an Agent

​Agent Builder

​Configuring a Model

​Provider Configuration

​Sending Prompts

​Chat and Conversation

​Structured Output

​Streaming

​Adding Tools

​Tool Registry

​Adding Memory

​Adding Knowledge

​Adding a Retriever

​Middleware

​Events, Hooks, and Callbacks

​Execution Configuration

​Agent Context

​Agent Delegation

​RAG-Enabled Agents

​Agents in Workflows

​Direct Agent Construction

​Complete Basic Example

​Agent Development Flow

​Next Steps

First Agent

Creating an Agent

Agent Builder

Configuring a Model

Provider Configuration

Sending Prompts

Chat and Conversation

Structured Output

Streaming

Adding Tools

Tool Registry

Adding Memory

Adding Knowledge

Adding a Retriever

Middleware

Events, Hooks, and Callbacks

Execution Configuration

Agent Context

Agent Delegation

RAG-Enabled Agents

Agents in Workflows

Direct Agent Construction

Complete Basic Example

Agent Development Flow

Next Steps